Skip to content

MkList

Show source on GitHub

Node for showing a formatted list.

Example: Regular

Jinja

{{ ["Item 1", "Item 2", "Item 3"] | MkList }}

Python

MkList([MkText('Item 1'), MkText('Item 2'), MkText('Item 3')])
  • Item 1
  • Item 2
  • Item 3
  * Item 1
  * Item 2
  * Item 3

<ul><li>Item 1</li><li>Item 2</li><li>Item 3</li></ul>

MkList
├── MkText('Item 1')
├── MkText('Item 2')
╰── MkText('Item 3')

Example: Shorten

Jinja

{{ ["Item 1", "Item 2", "Item 3"] | MkList(shorten_after=2) }}

Python

MkList([MkText('Item 1'), MkText('Item 2'), MkText('Item 3')], shorten_after=2)
  • Item 1
  • Item 2
  • ...
  * Item 1
  * Item 2
  * ...

<ul><li>Item 1</li><li>Item 2</li><li>...</li></ul>

MkList
├── MkText('Item 1')
├── MkText('Item 2')
╰── MkText('Item 3')

Example: Ordered

Jinja

{{ ["Item 1", "Item 2", "Item 3"] | MkList(ordered=True) }}

Python

MkList([MkText('Item 1'), MkText('Item 2'), MkText('Item 3')], ordered=True)
  1. Item 1
  2. Item 2
  3. Item 3
  1. Item 1
  2. Item 2
  3. Item 3

<ol><li>Item 1</li><li>Item 2</li><li>Item 3</li></ol>

MkList
├── MkText('Item 1')
├── MkText('Item 2')
╰── MkText('Item 3')

Example: Nested

Jinja

{{ [_mk.MkAdmonition("Nested!")] | MkList }}

Python

MkList([list([...])])

  • Info

    Nested!
  * !!! info
    Nested!

<ul><li>!!! info
    Nested!
</li></ul>

MkList
╰── MkAdmonition('Nested!')
    ╰── MkText('Nested!')

Bases: MkContainer

__init__ 

__init__(
    items: Sequence[str | mknode.MkNode] | None = None,
    *,
    ordered: bool = False,
    shorten_after: int | None = None,
    as_links: bool = False,
    **kwargs: Any
)

Parameters:

Name Type Description Default
items Sequence[str | MkNode] | None

Items to show as a list

 None
ordered bool

whether the list should be numbered

 False
shorten_after int | None

will clip the list after n items and append a "..."

 None
as_links bool

will convert the label to links which will get replaced by plugin

 False
kwargs Any

Keyword arguments passed to parent

 {}

to_html 

to_html() -> str
Name Children Inherits
MkContainer
mknodes.basenodes.mkcontainer
A node containing other MkNodes.		 
graph TD
  94854582943200["mklist.MkList"]
  94854582919984["mkcontainer.MkContainer"]
  94854582916880["mknode.MkNode"]
  94854582838576["node.Node"]
  140544995341632["builtins.object"]
  94854582919984 --> 94854582943200
  94854582916880 --> 94854582919984
  94854582838576 --> 94854582916880
  140544995341632 --> 94854582838576
/home/runner/work/mknodes/mknodes/mknodes/basenodes/mklist/metadata.toml
[metadata]
name = "MkList"
group = "container"
icon = "octicon:list-unordered-24"

[requirements.extension.def_list]

[examples.regular]
title = "Regular"
jinja = """
{{ ["Item 1", "Item 2", "Item 3"] | MkList }}
"""

[examples.shorten]
title = "Shorten"
jinja = """
{{ ["Item 1", "Item 2", "Item 3"] | MkList(shorten_after=2) }}
"""

[examples.ordered]
title = "Ordered"
jinja = """
{{ ["Item 1", "Item 2", "Item 3"] | MkList(ordered=True) }}
"""

[examples.nested]
title = "Nested"
jinja = """
{{ [_mk.MkAdmonition("Nested!")] | MkList }}
"""

[output.markdown]
template = """
{% for item in node.items[: node.shorten_after] %}
  {{ (loop.index ~ ".") if node.ordered else "*" }} {{ node._prep(item)}}
{% endfor %}
{% if node.shorten_after and node.items | length > node.shorten_after %}
  {{ (node.shorten_after + 1 ~ ".") if node.ordered else "*" }} ...
{% endif %}

"""

[output.html]
template = """
<{{ "ol" if node.ordered else "ul" }}>{% for item in node.items[: node.shorten_after] %}<li>{{ node._prep(item)}}</li>{% endfor %}
{% if node.shorten_after and node.items | length > node.shorten_after %}
<li>...</li>{% endif %}
</{{ "ol" if node.ordered else "ul" }}>
"""
mknodes.basenodes.mklist.MkList
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
class MkList(mkcontainer.MkContainer):
    """Node for showing a formatted list."""

    ICON = "octicons/list-unordered-24"
    REQUIRED_EXTENSIONS = [resources.Extension("def_list")]

    def __init__(
        self,
        items: Sequence[str | mknode.MkNode] | None = None,
        *,
        ordered: bool = False,
        shorten_after: int | None = None,
        as_links: bool = False,
        **kwargs: Any,
    ):
        """Constructor.

        Arguments:
            items: Items to show as a list
            ordered: whether the list should be numbered
            shorten_after: will clip the list after n items and append a "..."
            as_links: will convert the label to links which will get replaced by plugin
            kwargs: Keyword arguments passed to parent
        """
        # if as_links:
        #     items = [link.Link(i) for i in items]
        items = items or []
        self.ordered = ordered
        self.shorten_after = shorten_after
        self.as_links = as_links
        super().__init__(content=list(items), **kwargs)

    def _prep(self, item) -> str:
        return linkprovider.linked(str(item)) if self.as_links else str(item)

    def _to_markdown(self) -> str:
        if not self.items:
            return ""
        lines = [
            f"  {f'{i}.' if self.ordered else '*'} {self._prep(item)}"
            for i, item in enumerate(self.items[: self.shorten_after], start=1)
        ]
        if self.shorten_after and len(self.items) > self.shorten_after:
            prefix = f"{self.shorten_after + 1}." if self.ordered else "*"
            lines.append(f"  {prefix} ...")
        return "\n".join(lines) + "\n"

    def to_html(self) -> str:
        """Formats list in html as one single line.

        Can be useful for including in Tables.
        """
        if not self.items:
            return ""
        tag_name = "ol" if self.ordered else "ul"
        items = [f"<li>{self._prep(i)}</li>" for i in self.items[: self.shorten_after]]
        item_str = "".join(items)
        if self.shorten_after and len(self.items) > self.shorten_after:
            item_str += "<li>...</li>"
        return f"<{tag_name}>{item_str}</{tag_name}>"